Use logging in the decommutator and return a DecommutationResult - #87

Description

Replace the decommutator's hand-rolled log file (_statusmsg and the module-level logfile), print calls, and sys.stdout.write progress display with the logging module, using pyfaradaycup.configure_logging from #89. Also make swp_spc_l0_to_l05.main return a DecommutationResult and log provenance.

• ccsds_reader_pipeline, swp_spc_l0_to_l05, and main each have their own module logger, so the decommutator is silent from Python unless logging is configured.
• swp_spc_l0_to_l05.main no longer takes logdir or verbose, and no longer writes a log file itself. It logs provenance (software versions, host, working directory, the L0 file's size and SHA-256 checksum, and the kernels and skeletons used) and a summary.
• main returns a frozen DecommutationResult dataclass with the CDF files written, the APIDs that failed and why, packet counts, the same provenance, and the elapsed time. result.succeeded is False if any APID failed.
• pfc_decommutator calls configure_logging:
  • -v prints progress, -vv prints details, and -q prints only errors. Warnings are printed by default, and -v with -q is a usage error.
  • The log file always has every message, and is named like swp_spc_l0_to_l05_0523462910_4_EA_20261029T190014Z.log. It is opened with file_mode="exclusive", so runs cannot overwrite each other's logs.
  • The command and its options, Python warnings, and the warnings about options with no effect go to the log file too.
  • An unexpected error is logged with its traceback, and the exit code is 1. The exit code is also 1 when any APID could not be converted.
• In the CCSDS reader, each rejected packet is logged at DEBUG with its byte offset, and the reader logs one summary of packets found per APID and rejections per reason. The verbose arguments of the private reader and CDF writer functions are removed.
• The decommutator README is updated to drop the items this PR does, and to add follow-up items: writing provenance to CDF global attributes, comparing CDF attributes in the end-to-end test, and log improvements (APID/L0 file tagging, JSON Lines, multi-process logging).

Motivation

The decommutator will have both a Python API and a CLI, and will run in a Dagster pipeline. It needs to:

• leave the caller in control of where messages go,
• record enough provenance to trace each L0.5 file back to its inputs and software, and
• report failures through return values and exit codes, not only in log text.

This addresses "Return what was written", "Give each run its own log file name", and the logging part of "Make it callable from Python" in the decommutator README.

Details

Behavior changes for reviewers to check:

1. The exit code is now 1 when an APID is skipped, including APID 0x07B, which is not implemented and only appears with --spacecraft. Previously these runs exited with 0.
2. Log file timestamps are in UTC rather than local time, and the log file name format has changed.
3. The Python API has changed: main no longer accepts logdir or verbose and now returns a DecommutationResult instead of None, and the private reader and CDF writer functions no longer accept verbose.
4. Errors for a failed APID are logged at ERROR (one was previously a warning). Per-packet IT+ST and APID 0x352 problems are now DEBUG messages, plus one WARNING summary per APID.
5. The progress display (% Complete) has been removed.

Not done here:

• The warnings.warn in _parse_ccsds_head is unchanged.
• Provenance is not yet written to CDF global attributes.
• The spacecraft housekeeping (--spacecraft) path still has no end-to-end test.

Tests cover packet rejection logging and the packet summary, the CLI's log file and its contents, exit codes for an unexpected error and a failed APID, -v/-q, the console level for each verbosity, the warnings about ineffective options, a Python API run that checks the returned result and that nothing is printed, and that each decommutator module has its own logger.

🤖 Generated with Claude Code